<HTML><HEAD><TITLE>coverof(?Term, +Goal, -List)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">All Solutions</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>coverof(?Term, +Goal, -List)</H1>
Succeeds if List is the (non-empty) list of all the most general instances
of Term such that Goal is provable.


<DL>
<DT><EM>Term</EM></DT>
<DD>Prolog term, usually a variable, a compound term or list                containing variables.
</DD>
<DT><EM>Goal</EM></DT>
<DD>Callable term.
</DD>
<DT><EM>List</EM></DT>
<DD>List or variable.
</DD>
</DL>
<H2>Description</H2>
   Unifies List with the list (not ordered, duplicates removed, pruned) of
   all instances of Term such that Goal is satisfied.  prune_instances/2 is
   used on the list of solutions, with the result that no element of List
   is an instance of any other element.

<P>
   The variables appearing in Term should not appear anywhere else in the
   clause except within Goal.

<P>
   The following table illustrates the difference between the all solutions
   predicates:

<P>
<PRE>
    built-in  choice pts  duplicates  sorted pruned *
    bagof/3   yes         yes         no     no
    coverof/3 yes         no          no     yes
    findall/3 no          yes         no     no
    setof/3   yes         no          yes    no
   * prune_instances/2 used on list of solutions.
</PRE>
   If Goal is not a callable term, exceptions are raised in call/2.

<P>
   coverof/3 should not be used if Term is a variable.  If the resulting
   list List contains no compound terms or variables, it is usually more
   efficient to use setof/3.

<P>
Note
   If there are uninstantiated variables in Goal which do not appear in
   Term, then coverof/3  can be resatisfied.  It generates alternative
   values for List corresponding to different instantiations of the free
   variables of Goal not in Term.  Such variables occurring in Goal will
   not be treated as free if they are explicitly bound within Goal through
   an existential quantification written as, for example,

<P>
<PRE>
   coverof(X, Y^(X likes Y), S).
</PRE>
   Then coverof/3 will not backtrack over Y when getting a list of
   solutions of X.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>coverof(?, +, -) is nondet
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Fail Conditions</H3>
Fails if Goal has no solution
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Goal is not instantiated.
<DT><EM>(5) type error </EM>
<DD>Goal is instantiated, but not to a compound term.
<DT><EM>(68) calling an undefined procedure </EM>
<DD>Goal is an undefined procedure.
</DL>
<H2>Examples</H2>
<PRE>
Success:


   % example using existential quantification:
  [eclipse]: [user].
   h(f(1,2),g(1,3)).
   h(f(2,3),g(2,4)).
   h(f(1,3),g(2,2)).
   h(f(2,3),g(2,2)).
   h(f(2,2),g(1,1)).
   user compiled 900 bytes in 0.00 seconds

  yes.
  [eclipse]: coverof(f(X,Y),h(f(X,Y),g(W,Z)),L),
  &gt; writeln((X,Y,W,Z,L)), fail.
  _g66 , _g72 , 1 , 1 , [f(2, 2)]
  _g66 , _g72 , 1 , 3 , [f(1, 2)]
  _g66 , _g72 , 2 , 2 , [f(1, 3), f(2, 3)]
  _g66 , _g72 , 2 , 4 , [f(2, 3)]

  no (more) solution.
  [eclipse]: coverof(f(X,Y),g(W,Z)^h(f(X,Y),g(W,Z)),L).
  X = _g76
  Y = _g78
  W = _g70
  Z = _g72
  L = [f(1, 2), f(2, 3), f(1, 3), f(2, 2)]
  yes.
Fail:
  coverof(Y,current_stream(X,Y,Z),[strin]).
Error:
  coverof(X,G,L).         (Error 4).
  coverof(X,"G",L).       (Error 5).
  coverof(X,a,L).         (Error 68).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/allsols/bagof-3.html">bagof / 3</A>, <A HREF="../../kernel/allsols/findall-3.html">findall / 3</A>, <A HREF="../../kernel/allsols/setof-3.html">setof / 3</A>
</BODY></HTML>
